\documentclass[12pt,spanish]{article}
\usepackage[spanish,activeacute]{babel}
\usepackage[latin1]{inputenc}
\oddsidemargin 0in
\textwidth 6.75in
\topmargin 0in
\textheight 8.5in
\parindent 0em
\parskip 2ex
\usepackage{graphicx}
\begin{document}

\begin{center}
{\LARGE\bf DOCUMENTACI'ON de 'wwwpayaso'\\ }
\end{center}

\begin{center}
\hfill 15 de agosto de 2007 \\
\hfill Version 0.1
\end{center}

\section{Introducci'on}
Con este manual se prentende explicar todo lo relacionado al proyecto de la
construcci'on de una p'agina web mediante la utilizaci'on de
Python \footnote{http://www.python.org/} y el excelente framework
\footnote{http://es.wikipedia.org/wiki/Framework} (desarrollado en este mismo
lenguaje) TurboGears \footnote{http://www.turbogears.org/}.\\
Trataremos de explicar todo lo referente al proyecto desde c'omo se conforma
la estructura de las tablas de la base de datos hasta qu'e realiza cada
funci'on espec'ificamente.\\
La realizaci'on del proyecto se divide en tres grandes partes: {\em Modelo,
Vista y Controlador} \footnote{http://es.wikipedia.org/wiki/MVC}; las cuales
explicaremos a medida que vayamos avanzando en cada una de las secciones de este
manual.

\section{Python}
\subsection{Introducci'on}
Python es un lenguaje de programaci'on orientado a objetos, el cual puede
ser utilizado por muchas clases desarrolladores de software. Este ofrece un gran
soporte para la integraci'on con otros leguajes y herramientas, trae consigo
una gran biblioteca est'andar, y puede ser aprendido en pocos d'ias.\\
Python corre bajo Windows, Linux/Unix, Max OS X, OS/2, Amiga, Palm Hanhelds y
tel'efonos m'oviles Nokia. Es distribuido bajo una licencia de c'odigo abierto
lo cual es de uso {\em libre} incluso para productos comerciales.

\subsection{Convenciones}
En esta secci'on mencionaremos algunas conveniciones que tendremos en cuenta
para la creaci'on del proyecto y poder llevarlo adelante de la mejor manera
posible; tratando de respetar est'andares y estilos de programaci'on. Con lo
cual el c'odigo ser'a lo m'as legible posible haciendo que los integrantes del
proyecto se entiendan estando a distancia y sin m'as que la simple explicaci'on
de las cosas por el c'odigo mismo.

\begin{description}
    \item [estilo] seguiremos en todo lo posible lo que dice el art'iculo
\footnote{http://python.net/~goodger/projects/pycon/2007/idiomatic/handout.html}
de {\em David Goodger}. Tambi'en para el estilo de programaci'on seguiremos la
PEP 8 (Python Enhancement Proposals) \footnote{Ingl'es:
http://www.python.org/dev/peps/pep-0008/\\ Castellano:
http://mundogeek.net/traducciones/guia-estilo-python.htm} De esta gu'ia dejamos
en claro lo que quiz'as m'as se presta a confuci'on.

    \begin{itemize}
        \item Una l'inea en blanco entre definici'on de funciones.
        \item Dos l'ineas en blanco entre las definiciones de clases.
        \item Para la inserci'on de {\em Docstrings} utilizamos las tripes
comillas dobles, dejando una l'inea en blanco antes de la primer palabra
y despu'es de la 'ultima.
        \item Los nombres de las funciones, variables, clases y dem'as estar'an
en ingl'es, para una mejor comprensi'on en el resto de las personas debido al
alcance que tiene el mismo.
        \item En cada archivo {\em .py} en la primera l'inea se le colocar'a la
referecia {\em \#!/usr/bin/env python} para poder hacer de este ejecutable, y
en la segunda l'inea {\em \# -*- coding: utf-8 -*-} que indica cu'al es la
codificaci'on que vamos a utilizar en el archivo.
    \end{itemize}

    \item [parametros TurboGears] para todas las funciones hechas en TurboGears
en las cuales estas reciban par'ametros los mismos ser'an pasados de la forma
"bonita" respetando lo que dice la documentaci'on oficial
\footnote{http://docs.turbogears.org/1.0/GettingStarted/Arguments}. De esta
manera si queremos pasar dos argumentos a la funci'on {\em index}, por ejemplo,
lo hacemos de la siguiente manera:

\begin{verbatim}
http://localhost:8080/index/Manuel/Kaufmann
\end{verbatim}

Por lo que la funci'on {\em index} est'a recibiendo en el primer argumento la
cadena {\em Manuel} y en el segundo {\em Kaufmann}.

\end{description}

\section{TurboGears}
\subsection{Introducci'on}
En esta secci'on se encuentra todo lo que est'e relacionado con TurboGears en
lo que hemos tenido problemas al implementar en el dise~no de la p'agina c'omo
toda informaci'on que nos ha parecido 'util al momento de programar utilizando
este framework.\\
TurboGears trabaja con una base de datos SQL la cual es {\em mapeada} por una
biblioteca muy popular ultimamente, llamada SQLObject
\footnote{http://www.sqlobject.org/}. La cual nos permite crear todo tipo de
tablas, seleccionar la informaci'on que deseemos y dem'as, sin escribir ninguna
sentecia SQL.\\
Este framework utiliza mucho lo que en Python se conoce como {\em decoradores}
\footnote{http://wiki.python.org/moin/PythonDecoratorLibrary}; en el
desarrollo de la web los utilizamos para poder vincular las direcciones de la
{\em barra de direcciones} con los m'etodos apropiados para cada una de estas,
por ejemplo.

\subsection{Instalaci'on}

Antes de empezar debemos instalar TurboGears (actualmente se encuentra
disponible la versi'on 1.0). Para esto descargamos el archivo
{\em http://www.turbogears.org/download/tgsetup.py} y luego en una consola
hacemos:

\begin{verbatim}
[manuel] [~]$ python tgsetup.py
\end{verbatim}

Al ejecutar este comando descarga e instala todo lo necesario para poder
empezar a utilizar TurboGears perfectamente. Luego de instalar todo
correctamente para comenzar un proyecto hacemos:

\begin{verbatim}
[manuel] [~]$ tg-admin quickstart
Enter project name: wwwpayaso
Enter package name [wwwpayaso]:
Do you need Identity (usernames/passwords) in this project? [no]
\end{verbatim}

Lo que nos crea un proyecto llamado {\em wwwpayaso}, que es el nombre que
nosotros le dimos. Este comando genera toda una estructura de directorios y
archivos para que podamos comenzar a trabajar facilmente.

\subsection{Primer vistazo}

Luego de elegir el nombre y crear correctamente el proyecto, podemos entrar al
directorio que nos cre'o este comando y ver la lista de archivos que nos
gener'o; explicamos en detalle los m'as importantes.

\begin{description}
    \item [dev.cfg] {\em archivo de configuraci'on} contiene la informaci'on
sobre qu'e base de datos utilizaremos, el puerto en que se van a escuchar las
peticiones del explorador y la configuraci'on del sistema de loggin.
    \item [setup.py] {\em montaje} se utiliza para la configuraci'on del
proyecto en el directorio actual. Generalmente se lo ejecuta antes de empezar a
trabajar en el proyecto..
    \item [start-wwwpayaso.py] {\em webserver} es el servidor web, el cual debe
ser iniciado antes de poder visualizar la p'agina que hemos creado.
    \item [wwwpayaso/model.py] {\em modelo} en este archivo se debe poner todo
lo referido al modelo. Las tablas de la base de datos se encuentran en este
archivo.
    \item [wwwpayaso/templates] {\em vista} este directorio contiene todos las
plantillas XHTML con extenci'on {\em .kid} las cuales son las que se mostrar'an
cuando el usuario solicite una p'agina.
    \item [wwwpayaso/controllers.py] {\em controlador} aqu'i se crean todos los
m'etodos a los cuales la p'agina debe responder. En otras palabras est'an todas
las funciones que necesita el sistema para poder funcionar.
    \item [wwwpayaso/static] {\em images, css, etc} en este directorio se
encuentran todos los datos que son est'aticos, como ser las im'agenes que se
mostrar'an en la web o las hojas de estilos CSS, por ejemplo.
\end{description}

Veamos c'omo se ve la primer p'agina de ejemplo que se genera cuando se crea el
proyecto. Para esto abrimos una consola y tipeamos:

\begin{verbatim}
[manuel] [~/wwwpayaso]$ ./start-wwwpayaso.py
2007-08-15 21:57:25,773 cherrypy.msg INFO CONFIG: Server parameters:
2007-08-15 21:57:25,774 cherrypy.msg INFO CONFIG:   server.environment:
development
2007-08-15 21:57:25,774 cherrypy.msg INFO CONFIG:   server.log_to_screen: True
2007-08-15 21:57:25,775 cherrypy.msg INFO CONFIG:   server.log_file:
2007-08-15 21:57:25,775 cherrypy.msg INFO CONFIG:   server.log_tracebacks: True
2007-08-15 21:57:25,775 cherrypy.msg INFO CONFIG:   server.log_request_headers:
True
2007-08-15 21:57:25,775 cherrypy.msg INFO CONFIG:   server.protocol_version:
HTTP/1.0
2007-08-15 21:57:25,776 cherrypy.msg INFO CONFIG:   server.socket_host:
2007-08-15 21:57:25,776 cherrypy.msg INFO CONFIG:   server.socket_port: 8080
2007-08-15 21:57:25,776 cherrypy.msg INFO CONFIG:   server.socket_file:
2007-08-15 21:57:25,776 cherrypy.msg INFO CONFIG:   server.reverse_dns: False
2007-08-15 21:57:25,777 cherrypy.msg INFO CONFIG:   server.socket_queue_size: 5
2007-08-15 21:57:25,777 cherrypy.msg INFO CONFIG:   server.thread_pool: 10
2007-08-15 21:57:25,942 cherrypy.msg INFO HTTP: Serving HTTP on
http://localhost:8080/
\end{verbatim}

Lo que nos indica en la 'ultima l'inea es que est'a escuchando las
peticiones en la direcci'on {\em http://localhost} en el puerto {\em 8080}.
Para acceder a la p'agina principal vamos a un navegador, en mi caso Mozilla
Firefox
\footnote{http://www.mozilla-europe.org/es/products/firefox/}, y ponemos en la
barra de direcciones {\em http://localhost:8080}; lo cual visulizar'a algo
parecido a la Figura ~\ref{fig:welcome}. Lo que nos indica que el proyecto est'a
funcionando correctamente y el servidor web est'a bien configurado. Si logramos
esto tenemos un buen comienzo, y eso no es poco en estos temas.

\begin{figure}
\centering
\includegraphics[scale=0.25]{images/fig-01.eps}
\caption{{\small Welcome To TurboGears}}
\label{fig:welcome}
\end{figure}


\subsection{{\em Modelo}: base de datos con SQLObject}

\subsubsection{Conexi'on de la base de datos}

La parte del modelo la desarrollamos con una base de datos MySQL
\footnote{http://www.mysql.com/} ya que el hosting que vamos a
adquirir nos brinda este servicio y no SQLite \footnote{http://www.sqlite.org/}
por ejemplo.\\
En la base de datos guardaremos toda la informaci'on que necesitemos manejar y
mostrar en nuestra p'agina. Para esto necesitamos editar el archivo {\em
dev.cfg} y buscar la l'inea que dice:

\begin{verbatim}
# sqlobject.dburi="postgres://username@hostname/databasename"
# sqlobject.dburi="mysql://username:password@hostname:port/databasename"
# sqlobject.dburi="sqlite:///file_name_and_path"
\end{verbatim}

La l'inea del medio es la que tenemos que modificar si es que queremos utilizar
MySQL como es en nuestro caso. Primero descomentamos la l'inea y ponemos el
{\em username, password, hostname, port, databasename} para que funcione todo
correctamente. Dejando todo esto entre comillas dobles, como est'a
actualmente. Debemos tener los permisos suficientes para poder utilizar esta
base de datos como usuario. En mi caso, la l'inea me qued'o as'i:
\begin{verbatim}
sqlobject.dburi="mysql://manuel@localhost:3306/wwwpayaso"
\end{verbatim}

Seguido de esto debemos comentar la l'inea que se muestra a continuaci'on ya
que por defecto TurboGears est'a configurado para utilizar SQLite.

\begin{verbatim}
sqlobject.dburi="sqlite://%(current_dir_uri)s/devdata.sqlite"
\end{verbatim}

\subsubsection{Creaci'on de la base de datos}

Ahora pasemos a crear las tablas correspondientes a la informaci'on que
necesitamos guardar en la base de datos. Para esto vamos al archivo antes
mencionado {\em model.py} y creamos una nueva clase que hereda de {\em
SQLObject}; veamos c'omo queda nuestro c'odigo:

\begin{verbatim}
class Photo(SQLObject):
    disco = UnicodeCol(notNone=True)
    date = DateCol(notNone=True)
    image = UnicodeCol(notNone=True)
    thumbail = UnicodeCol(notNone=True)
\end{verbatim}

\begin{description}
    \item [Photo] nombre de la tabla SQL.
    \item [disco] nombre de la discoteca, bar, pub, etc en la cual fu'e tomada
la fotograf'ia.
    \item [date] fecha en la cu'al fu'e tomada la fotograf'ia.
    \item [image] direcci'on relativa en la que se encuentra la imagen en
tama~no real.
    \item [thumbail] direcci'on relativa en la que se encuentra la imagen en
tama~no real.
\end{description}

{\em Nota}: las direcciones de las im'agenes son relativas, comenzando desde la
direcci'on en la que se encuentra el proyecto; en nuesto caso se ubicar'ian en:
{\em ./wwwpayaso/static/images/photos/}

Ahora debemos crear esta tabla para poder comenzar a utilizarla. Esto lo
hacemos con el siguiente comando desde una consola:

\begin{verbatim}
[manuel] [~/wwwpayaso]$ tg-admin sql create
Using database URI mysql://manuel@localhost:3306/wwwpayaso
[manuel] [~/wwwpayaso]$ 
\end{verbatim}

Esta es s'olo una de las clases que necesitamos para nuestro modelo, las dem'as
se creean de la misma manera y ser'an mostradas m'as adelante en el transcurso
de las secciones.

\subsubsection{Manejo de la base de datos}

Para agregar una foto a la base de datos basta con iniciar un int'erprete python
con el comando {\em tg-admin} de TurboGears para que cargue autom'aticamente
todos los m'odulos necesarios, en otras palabras, carga todo nuestro proyecto.
El comando es el siguiente:

\begin{verbatim}
[manuel] [~/wwwpayaso]$ tg-admin shell
Python 2.5.1 (r251:54863, May  2 2007, 16:27:44)
Type "copyright", "credits" or "license" for more information.

IPython 0.7.3 -- An enhanced Interactive Python.
?       -> Introduction to IPython's features.
%magic  -> Information about IPython's 'magic' % functions.
help    -> Python's own help system.
object? -> Details about 'object'. ?object also works, ?? prints more.

In [1]: import datetime

In [2]:
Photo(disco="baucis",date=datetime.date.today(),
image="static/images/someimage.jpg",
thumbail="static/images/thumbail/somethumbail.jpg")
Out[2]: <Photo 26 disco=u'baucis' date='datetime.date(200...)'
image="u'static/images/s...'" thumbail="u'static/images/t...'">

In [3]: Photo.get(1)
Out[3]: <Photo 26 disco=u'baucis' date='datetime.date(200...)'
image="u'static/images/s...'" thumbail="u'static/images/t...'">
\end{verbatim}

Esto quiere decir que ingresamos una foto a la tabla {\em Photo} con los datos
que le pasamos por argumento {\em In [2]: Photo(...)} y luego adquirimos la foto
que acabamos de ingresar {\em In [3]: Photo.get(1)}.

La administraci'on de la base de datos la podemos hacer tambi'en a trav'es de
una interfaz web bast'ante amigable. Esta forma nos permite crear las tablas
necesarias y mientras ir viendo un diagrama de c'omo estar'ian relacionadas
entre s'i. Para realizar la creaci'on y modificaci'on de la base de datos
tipeamos en una consola:

\begin{verbatim}
[manuel] [~/www-payaso]$ tg-admin toolbox
\end{verbatim}

Lo que nos abre una pesata~na en el navegador, si es que lo tenemos abierto, o
directamente abre un nuevo navegador en la direcci'on {\em
http://localhost:7654/}, lo que se tiene que ver similar a la Figura
~\ref{fig:toolbox}. En esta p'agina podemos acceder a la secci'on {\em
ModelDesigner} para crear/dise~nar la base de datos o, si ya la hemos creado
anteriormente en el archivo {\em model.py}, vamos directamente a {\em CatWalk}.
Siguiendo lo que se muestra dentro de estas secciones es muy f'acil crear o
modificar todo lo necesario. Las otras secciones las explicaremos m'as adelante
en el cap'itulo.

\begin{figure}
\centering
\includegraphics[scale=0.25]{images/fig-02.eps}
\caption{{\small TurboGears Toolbox}}
\label{fig:toolbox}
\end{figure}

\subsection{{\em Vista}: XHTML, CSS y dem'as}

\subsubsection{Introducci'on}

Las p'aginas webs que utiliza TurboGears son contruidas mediantes el lenguaje
{\em XHTML} \footnote{http://es.wikipedia.org/wiki/XHTML} el cual permite
"dise~nar" lo que se mostrar'a en pantalla cuando el usuario ingrese la
direcci'on de esta en su navegador. Lo que se prentende aqu'i es simplemente
plasmar el {\em contenido} de la web y no el dise~no en lo que se refiere a
tipograf'ia y colores. Para esto se utilizar {\em CSS}
\footnote{http://es.wikipedia.org/wiki/Css} el cu'al permite con simples
atributos definir todo lo referido a colores, ubicaci'on de texto, fondo,
im'agenes, etc.

\subsection{{\em Controlador}: CherryPy}

\subsubsection{Introducci'on}

'Esta es una de las secciones m'as importantes ya que, no s'olo, mostraremos
realmente c'omo funciona nuestro proyecto, sino tambi'en explicaremos en
detalle cada una de las expresiones y funciones que se vayan necesitando a
medida que avancemos en el mismo.\\
CherryPy es el controlador de nuestro proyecto, es el v'inculo entre la vista y
el "motor" que se encuentra detr'as de la p'agina a simple vista. Cuando
nosotros colocamos la direcci'on de la p'agina en nuestro navegador este
consulta y dialoga con CherryPy el cu'al ejecuta c'odigo Python y devuelve las
respuestas nuevamente a la vista. Podemos ver 'esto de forma gr'afica en la
Figura ~\ref{fig:mvc}, d'onde se muestra la conexi'on entre cada uno de los
m'odulos que hemos ido explicando. En pocas palablas, y resumiendo lo explicado
en las secciones anteriores, cada uno de estos m'odulos se encarga de:

\begin{description}
    \item [Mochikit] es una librer'ia limpia y potente de {\em JavaScript}
    \item [Kid] es un dise~nador y amigable programador de los sistemas
de templates
    \item [CherryPy] hace posible la entrada y salida de nuestra web, de manera
tan f'acil como es escribir una funci'on en Python
\end{description}

\begin{figure}
\centering
\includegraphics[scale=0.9]{images/fig-03.eps}
\caption{{\small Modelo-Vista-Controlador}}
\label{fig:mvc}
\end{figure}

\subsubsection{Primer funci'on}
Al crear el proyecto, este crea los archivos que explicamos anteriormente. En
esta secci'on nos vamos a focalizar en {\em controllers.py}. Ya que es aqu'i
d'onde va todo el c'odigo Python para que nuestra web funcione correctamente.
Vamos a ver qu'e es lo que contiene este archivo al momento de ser creado.

\begin{verbatim}
from turbogears import controllers, expose, flash
# from model import *
# import logging
# log = logging.getLogger("wwwpayaso.controllers")

class Root(controllers.RootController):
    @expose(template="wwwpayaso.templates.welcome")
    def index(self):
        import time
        # log.debug("Happy TurboGears Controller Responding For Duty")
        flash("Your application is now running")
        return dict(now=time.ctime())
\end{verbatim}

En las primeras l'ineas importamos los m'odulos necsarios. Luego vemos una
definici'on de una clase que hereda de {\em controllers.RootController}. 'Esta
es la clase que se encarga de interpretar todas las direcciones que ingresemos
en la {\em barra de direcciones} de nuestro navegador.\\
Esta clase por defecto viene con la funci'on {\em index} definida; 'esta es la
que se llama cuando accedemos al {\em home} de nuestra web. En este caso cuando
pongamos la direcci'on {\em http://localhost:8080} la estar'iamos llamando.\\
Notemos que antes de la definici'on de la funci'on y despu'es de la
definici'on de la clase, vemos un decorador, {\em
@expose(template="wwwpayaso.templates.welcome)}, esto significa que est'amos
conectando esa funci'on con el template {\em welcome.kid} para que cuando
llamemos a esta funci'on lo que retorne sea pasado a esa p'agina y poder
realizar lo que queramos con el resultado. Podemos ver en detalle los
decoradores en los links de referecias.\\
La funci'on {\em index} retorna un diccionario de la forma \{now: "17-08-07
11:04:25"\}, esta informaci'on es utilizada en el template para mostrarla en la
p'agina. Todas las funciones en TurboGears deben retornar un {\em string,
diccionario o generador}; de otra forma el servidor web nos informar'a de dicho
error.

\subsubsection{Funciones para la base de datos}
A medida que vayamos desarrollado las funciones relacionadas con la base
de datos ser'an escritas en esta secci'on, sujetas a cualquier modificaci'on
que se presente a lo largo de la creaci'on del proyecto. Hasta el momento se
pueden describir las siguientes:

\begin{description}
    \item [update\_database(self)] se encarga de actualizar la base de datos,
lo que significa que agregar'a las direcciones de las fotos que no a'un no se
hallan cargado. Para esto recorre la direcci'on {\em
./wwwpayaso/static/images/photos} mediante la funci'on {\em os.walk()}
\end{description}

\newpage
\section{Referencias}
\begin{enumerate}
    \item {\em Manual XHTML} \hfill http://manual-xhtml.blogspot.com/
    \item {\em Tutorial CSS} \hfill
http://www.programacion.com/tutorial/csspractico/
    \item {\em SQLObject} \hfill http://www.sqlobject.org/
    \item {\em ImageMagick} \hfill http://www.imagemagick.org/
    \item {\em WebFaction} \hfill http://www.webfaction.com/
    \item {\em Nexcess} \hfill http://www.nexcess.net/
    \item {\em LaTeX} \hfill
http://www.fceia.unr.edu.ar/lcc/cdrom/Instalaciones/LaTex/latex.html/
\end{enumerate}


\end{document}